Workshop 2: RMarkdown

Workshop 2 - RMarkdown

The aim

We want to present the results and the visuals in ways that are easier to share with people. We will knit the RMarkdown file into a PDF or a webpage, so people can have all the info in one place (together with the code if it is a webpage).

What is RMarkdown?

RMarkdown is a file format to make dynamic documents in R. You can include analyses with outputs, graphs, text to explain your analysis, photos and hyperlinks. This page you are looking at right now is produced from an RMarkdown file! The RMarkdown file consists of text and chunks of code. This allows you to provide formatted explanations alongside your code and analysis.

Check out these useful links (below) to learn more.

Structure

As we have mentioned in the last workshop (or not), we suggest you to have some specific folders to keep everything tidy.

• data: your data
• scripts: for the scripts, including .R and .Rmd files
• docs: for the output
• images (optional): for the images

Knit into html

We will use RMarkdown to create a webpage and publish the page as a GitHub page online.

example 1 - Visual models

example 2 - Heating rate

Details

Let’s take a closer look what we can have in a website

1. Header

2. Table

3. Tabs

4. Code button

Essentials Files

There are two files you need to have to publish a webpage:

1. index.html: default homepage
2. _site.yml: essential if you want to have more than one page on your site. It provides the global YAML header for the site.

Exercise 1: Copy the Website repo from Bug of the week to your own GitHub.

html

Content page

You can create RMarkdown files and set the output into html format.
Where to set it?
You will set the output formate and appearance in the yaml header of your RMarkdown file.
What and where is the yaml header?
In (very) short, it controls the overall appearance of the page and it is on the top of the file like this:

---
title: "Workshop 2: RMarkdown"
author: "Amanda Franklin, Laura Ospina, Lu-Yi Wang"
date: "4/25/2022"
output: html_document
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })
---

See here and here for more details about yaml.

Note: You would like to save your output html files in the docs folder. To do so, you will need to change the directory in the yaml header using the following code:

knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })

Exercise 2: Create 2 RMarkdown pages. Knit them into html and save them in the docs folder. Try to apply the syntax Amanda just showed you.

For making buttons, you can use the following code after #, then the headers of the immediate lower level will turn into tabs.

{.tabset .tabset-fade .tabset-pills}

#e.g. 

## Header 2 {.tabset .tabset-fade .tabset-pills}

### Header 3.1 
bla bla bla 

### Header 3.2
bla bla bla 

# Here, you will get two tabs which are "Header 3.1" and "Header 3.2"

Index page

Remember that we need a index.html file for the homepage? You can either assgin one of the pages you create as the homepage by changing the name of the corresponding .Rmd file to index and knit it again, or you can create a new .Rmd file and call it index.

To link to the other page, you an use the following code

[text](html file name/http address)

# For example, if in the same folder 
# [Workshop 1: Github](workshopGithub.html) 
# Or [Bug of the week](https://github.com/bugoftheweek)

Exercise 3: Make your index.html file and try to link it to the pages you just made.

yml

We have created two separate pages. How do we combine them into one site?
To do this, we need the _site.yml file (need to be specifically called _site.yml).

1. Create a text file

Note: You need to place the _site.yml file in the same folder as other .Rmd files

2. Change the file type to .yml by adding “.yml” at the end of the file. After this, open the .yml file from RStudio instead of directly from the folder.

3. Inside the _site.yml file Whatever you put here will overwrite the ymal header in the separate .Rmd files. In side the file, we will specify things including the headers, the table, the theme, and the output directory.

Note: you need to set the output directory to the same folder (docs) as other html to be able to combine them into one site

name: "Lab Workshop"
navbar:
  title: ""
  subtitle: Supplementary Information
  Date: "April 25th 2022"
  left: # left side of the header
  - text: "Introduction"
    href: index.html
  - text: "Workshop 1: Github"
    href: workshopGithub.html
  - text: "Workshop 2: RMarkdown"
    href: workshopRMarkdown.html
  right: # right side of the header
  - icon: fa-github # icon of GitHub
    text: Bug of the week
    href: https://github.com/bugoftheweek # You can also have a http address 
      
output:
  html_document:
    toc: true # table of content true
    toc_float: # have a table of content at the left side
      collapsed: true # default true, only show up tp level 2 unless click to expand
      smooth_scroll: true # animated the page to the clicked item
    depth: 6  # up to three depths of headings (specified by #, ## and ###)
    number_sections: false  #  number sections at each table header
    theme: flatly # theme for fonts and colours
    highlight: tango # different theme for the appearance of the code
output_dir: "../docs"

Exercise 4: Make some edits (e.g. headers) in your _site.yml file!

Publish it!

Now we are going to make the site go online!

1. Be sure your repo is public. If not, got to Setting -> Genral -> scroll to the end.

2. In the Setting, on the left table, click Pages

3. Change the branch to “main” and the folder to “docs” cause that is where the index.html is.

4. You made it! But it will take a couple minutes till the link starts to work.

Exercise 4: Try to publish your page!

Knit into a PDF

To knit into a PDF, you don’t need the .yml file. All you need to do is to change the output format into “pdf_document”.

output: pdf_document

If you choose the output format to PDF upon creating the RMarkdown, it will automatically assign the output format to PDF. But you need to change the output directory to the docs folder manually on the yaml header.

To knit an RMkarkdown into PDF,you will need to install LaTeX on you computer. The simplest way is to install TinyTeX and you can run the following code from here in R to install it.

install.packages('tinytex')
tinytex::install_tinytex()

There are some difference in syntax between the two formats and some functions are available for html output but not for PDF one, e.g. tabs, code buttons. So they are not completely compatible.

If you want to include a content table on the first page of the PDF, you can add the following code in the yaml header:

output: 
  pdf_document:
    toc: true # To have the content table or not
    toc_depth: 3 # To which level of the headers you want to include

Exercise 5: Try to make one RMarkdown file and knit it into a PDF.

Note: If you put the .Rmd file that you want to knit into PDF in the same folder as your _site.yml, the .Rmd will be knitted into an html file because the yaml header in the _site.yml overrides the the ymal header in .Rmd files if they are in the same directory.
Hence, you need to create another script folder for the Rmd files that you want to knit into PDFs.

Useful links

For RMarkdown

1. RMarkdwon Introduction and Lesson
2. RMarkdown cheat sheet
3. R Markdown: The Definitive Guide
4. Tom Keaney’s Introduction to R markdown
5. Getting started with a RMarkdown

For kniting into html

1. R Markdown Websites

2. R Markdown: The Definitive Guide

3. Making websites

4. R Markdown Basics

Other awesome exmaple websites

Have useful code for some amazing features/figures.

1. Luke’s data page
2. Justin’s data page